Inside Macintosh: Open Transport /

Chapter 6 - Configuration Management

Using the Configuration Functions

This section describes how to determine whether Open Transport is
available, how to initialize all or some of Open Transport, how to
configure providers, how to obtain port information, and how to register
as an Open Transport client.

Determining Whether Open Transport Is Available

If you want to know if Open Transport is available on your computer, use the Gestalt function with 'otan' as its selector. If Gestalt returns no error and its response parameter returns with a value other than 0, Open Transport is available. To find out whether AppleTalk, TCP, or NetWare are present, you can examine the response parameter bits. For a list of the possible bit values, see the section "The Gestalt Selector and Response Bits" on page 6-15.

Initializing Open Transport

There are two Open Transport initialization functions: the InitOpenTransport and InitOpenTransportUtilities functions. To initialize all of Open Transport, you call the InitOpenTransport function, which loads the Open Transport modules.

If your application performs port manipulation and does not need to open or use any providers, you can use the InitOpenTransportUtilities function, which initializes only those Open Transport modules that handle ports.

Neither of these two functions, however, loads the AppleTalk or TCP/IP software modules. Open Transport automatically initializes the AppleTalk modules whenever you first open an endpoint, mapper or AppleTalk service provider; and it initializes TCP/IP whenever you open an endpoint or mapper for that protocol family.

Using Open Transport From a Client Application

If your client is an application, you must follow these steps to initialize the Open Transport software:

1. Include the Open Transport client header file, OpenTransport.h.
2. If you use the Apple Shared Library Manager (ASLM), call the InitLibraryManager function.
3. Call the InitOpenTransport (or InitOpenTransportUtilities) function.

When you are no longer using Open Transport, you can choose to unload the Open Transport software modules by using the CloseOpenTransport function. If you used ASLM, you can then call the CleanupLibraryManager function. Both of these functions are optional; the system automatically calls them if your application does not call them.

Using Open Transport From a Stand-Alone Code Segment

If your client is a stand-alone code segment or code fragments, you must follow these steps to initialize the Open Transport software:

1. Include the Open Transport client header file, OpenTransport.h.
2. Establish an A5 world if you are running on a 68000-family Macintosh computer. See the Apple Shared Library Manager Developer's Guide for details of how to do this.
3. If you use ASLM, call the InitLibraryManager function.
4. Call the InitOpenTransport (or InitOpenTransportUtilities) function.

Note

Stand-alone code segment clients that are on 68000-family Macintosh computers have to ensure that their A5 world is correct each time they call an Open Transport function.

When you are no longer using Open Transport, you can unload the Open Transport software modules. For stand-alone code segments, this means that you must call the CloseOpenTransport function before you unload from memory, and if you used ASLM, you must call the CleanupLibraryManager function.

System software cannot unload Open Transport until the last software
module on your computer that called the InitOpenTransport or InitOpenTransportUtilities function has also called the CloseOpenTransport function.

Creating and Reusing Provider Configurations

Once Open Transport is initialized, you need to configure any providers you want to use for transmitting and receiving data. To do this, you create a configuration structure with the OTCreateConfiguration function using a configuration string, as described in the section "About Provider Configurations," beginning on page 6-3.

You typically call the OTCreateConfiguration function inline while calling a function that creates and opens a provider (for example, the OTOpenEndpoint function). The function that opens providers checks whether the OTCreateConfiguration function returned ((OTConfiguration*)-1L) or NULL, and if so, returns an appropriate result code.

The open-provider functions take a pointer to the configuration structure as input, but as part of their processing, they destroy the original configuration structure. Since typically you use the OTCreateConfiguration function to create only a single provider at a time, this works fine most of the time. Occasionally, however, you may want to reuse a configuration structure to create a second identical provider, or you may want to reuse a configuration sent from another application for which you do not have the configuration string.

The only way to reuse a configuration structure is to clone it with the OTCloneConfiguration function before opening your first provider. In this way, you can save the provider's configuration to disk or make multiple copies of the same configuration.

For example, you might have only a pointer to a structure, but you want to create ten endpoints, and so you need ten structures. The moment you use the original pointer to create an endpoint, the structure is gone. You can't call
the OTCreateConfiguration function because you don't have the original configuration string; you were only passed the structure. However, if you can create a copy of the structure, you don't need the string; so you clone the original structure nine times before opening the first endpoint, which results in a total of ten identical configuration structures.

Obtaining Port Information

If your application manipulates ports, you may need port information to locate a specific port or to find out how what ports are registered for your computer. Open Transport registers all ports that are associated with your computer and creates a port structure for each port. You can then use the various Open Transport port functions to access these structures and get information from them. (The port structure is described in the section "The Port Structure," beginning on page 6-17.)

If you want to find out the port associated with a given provider, you can use the OTGetProviderPortRef function. If you don't know which port structure you want or if you want to provide a list of user-readable port names to your user, you can use the OTGetIndexedPort function to iterate through all the ports available on a computer, obtaining the port structure of each.

There are also two find functions you can use to find the port structure for a specific port: If you know its port name, you can use the OTFindPort function, or if you know its port reference, you can use the OTFindPortByRef function.

If you want to use the OTFindPortByRef function, you need a port reference. There are several ways you can get one: Another application might have passed it to you, another application could have put it into a port structure that you now access by using the OTGetIndexedPort function, or you can create one.

To create a port reference, you use the OTCreatePortRef function. You must know all the port's hardware characteristics: its device and bus type, its slot number, and its multiport identifier (if it has one). You cannot use wildcards to fill in any element you don't know. Possible device and bus types are described in "The Port Reference," beginning on page 6-19.

Note

Note that the slot numbers for NuBus(TM) cards are physical; that is, they are the slot numbers returned by the Slot Manager and not the slots seen in various network configuration applications. Physical slot numbers depend on the type of card installed. For example, NuBus cards number their slots 9 to 13, which appear in the AppleTalk or TCP control panels as slots 1 to 5. For PCI cards, however, the slot numbers are their logical slot IDs as defined in the port structure. For cards in a PCI bus, it is not possible, a priori, to create a port reference that corresponds to a known card, so applications must iterate through the port registry to find appropriate PCI ports.

For example, if you want to find out the port name of the Ethernet port in NuBus slot 13, you can use this line of code to create a port reference for this port:

OTPortRef ref = OTCreatePortRef(kOTNuBus, kOTEthernetDevice, 13, 0);

If you then pass the result of this call to the OTFindPortByRef function, OTFindPortByRef fills a buffer with the port structure that has this port reference and returns a pointer to the buffer. You can examine the port structure's fields for its port name.

Open Transport has predefined variants of the OTCreatePortRef function for the most commonly used hardware devices such as the NuBus, PCI, and PCMCIA devices. These are found in the section describing the function OTCreatePortRef (page 6-35).

If you want to extract information from a port reference, you have to use specific Open Transport functions: OTGetDeviceTypeFromPortRef, OTGetBusTypeFromPortRef, and OTGetSlotFromPortRef.

Requesting a Port to Yield Ownership

There may be times when you need to use a particular port that is owned by another provider. You can use the OTYieldPortRequest function to request the owner of a port (normally, a serial port or modem) to yield the use of the port to you. Open Transport then issues a kOTYieldPortRequest event to each provider of any registered clients for that port for acceptance or refusal. If the owner has not registered as a client of Open Transport, no event can be sent and acceptance is implicit.

If the current owner wants to deny the request, it puts a negative error code into the fDenyReason field in the port close structure indicating its reason for refusal. The OTYieldPortRequest function then returns with this error code as its result and with a buffer listing all the clients that have refused the request, (normally only one).

If the OTYieldPortRequest function returns without an error, the port is available for your use. You can then bind it with a queue length (qlen) greater than 0 or establish a connection with it. If you don't use the port within 10 seconds, the port automatically stops being available for your use and reverts to its original owner.

You can force a passive client to yield by using a value of NULL in the OTYieldPortRequest function's buffer parameter. When the function returns without an error, the port is available. Note that a port can only be yielded in this manner if its current client is passively listening; it cannot be yielded if a connection is in progress.

Providers owned by unregistered clients need to be prepared to receive kOTProviderIsDisconnected and kOTProviderIsReconnected events when the connection between the provider and port is unexpectedly disconnected and reconnected due to a successful yield reques.

Registering as an Open Transport Client

You can use the OTRegisterAsClient function to register your application as an Open Transport client and provide Open Transport with a notifier function for sending messages to you. Once you are registered as a client, Open Transport can notify you of system events, such as the port transition events that occur when a particular port is disabled or closed and when it is reenabled. By registering, you also provide Open Transport with a user-readable name to use when informing the user of port transition events.

This function is, however, optional. If you do not want to receive these events, you do not have to call this function.

If you did register your name, when you finish using Open Transport, you need to call the OTUnregisterAsClient function to remove your name as an available client. However, the CloseOpenTransport function automatically calls this function if you fail to do so.